Crate postgresql_embedded
source ·Expand description
§postgresql_embedded
Install and run a PostgreSQL database locally on Linux, MacOS or Windows. PostgreSQL can be bundled with your application, or downloaded on demand.
§Table of contents
§Examples
§Asynchronous API
use postgresql_embedded::{PostgreSQL, Result};
#[tokio::main]
async fn main() -> Result<()> {
let mut postgresql = PostgreSQL::default();
postgresql.setup().await?;
postgresql.start().await?;
let database_name = "test";
postgresql.create_database(database_name).await?;
postgresql.database_exists(database_name).await?;
postgresql.drop_database(database_name).await?;
postgresql.stop().await
}
§Synchronous API
#[cfg(feature = "blocking")] {
use postgresql_embedded::blocking::PostgreSQL;
let mut postgresql = PostgreSQL::default();
postgresql.setup().unwrap();
postgresql.start().unwrap();
let database_name = "test";
postgresql.create_database(database_name).unwrap();
postgresql.database_exists(database_name).unwrap();
postgresql.drop_database(database_name).unwrap();
postgresql.stop().unwrap();
}
§Information
During the build process, when the bundled
feature is enabled, the PostgreSQL binaries are
downloaded and included in the resulting binary. The version of the PostgreSQL binaries is
determined by the POSTGRESQL_VERSION
environment variable. If the POSTGRESQL_VERSION
environment variable is not set, then postgresql_archive::LATEST
will be used to determine the
version of the PostgreSQL binaries to download.
When downloading the PostgreSQL binaries, either during build, or at runtime, the GITHUB_TOKEN
environment variable can be set to a GitHub personal access token to increase the rate limit for
downloading the PostgreSQL binaries. The GITHUB_TOKEN
environment variable is not required.
At runtime, the PostgreSQL binaries are cached by default in the following directories:
- Unix:
$HOME/.theseus/postgresql
- Windows:
%USERPROFILE%\.theseus\postgresql
§Feature flags
postgresql_embedded uses feature flags to address compile time and binary size uses.
The following features are available:
Name | Description | Default? |
---|---|---|
bundled | Bundles the PostgreSQL archive into the resulting binary | No |
blocking | Enables the blocking API; requires tokio | No |
tokio | Enables using tokio for async | No |
§Safety
These crates use #![forbid(unsafe_code)]
to ensure everything is implemented in 100% safe Rust.
§License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
PostgreSQL is covered under The PostgreSQL License.
§Notes
Uses PostgreSQL binaries from theseus-rs/postgresql-binaries.
Modules§
Structs§
- PostgreSQL server
- Database settings
Enums§
- Errors that can occur when using PostgreSQL embedded
- PostgreSQL status
Type Aliases§
- PostgreSQL embedded result type